The Atari Compendium

home *** CD-ROM | disk | FTP | other *** search

/ The Atari Compendium / The Atari Compendium (Toad Computers) (1994).iso / files / prgtools / mint / mntdoc01.zoo / mintdoc / cat2 / fcntl.nr < prev next >

Wrap

Text File | 1993-03-03 | 17.1 KB | 463 lines

Fcntl(2) July 20, 1992 Fcntl(2) N✓NA✓AM✓ME✓E Fcntl - perform various control operations on a file S✓SY✓YN✓NO✓OP✓PS✓SI✓IS✓S #include <filesys.h> LONG Fcntl( WORD fh, LONG arg, WORD cmd); D✓DE✓ES✓SC✓CR✓RI✓IP✓PT✓TI✓IO✓ON✓N _✓F_✓c_✓n_✓t_✓l performs various control operations on the open file with GEMDOS file handle _✓f_✓h. The specific command to per- form is given by _✓c_✓m_✓d; the possible commands are given by symbolic constants in filesys.h, and are listed below. _✓a_✓r_✓g is an argument whose meaning depends on the command. The following commands are applicable to any file descrip- tor: F_DUPFD Return a duplicate for the file handle. The new (duplicate) handle will be an integer >= arg and < 32. If no free handles exist in that range, ENHNDL will be returned. The _✓F_✓d_✓u_✓p(_✓f_✓h) system call is equivalent to _✓F_✓c_✓n_✓t_✓l(_✓f_✓h, 6L, F_DUPFD) F_GETFD Return the noinherit flag for the file descriptor. This flag is 0 if child processes started by _✓P_✓e_✓x_✓e_✓c should inherit this open file, and 1 if they should not. _✓a_✓r_✓g is ignored. F_SETFD Set the noinherit flag for the file descriptor from the low order bit of _✓a_✓r_✓g. The default value of the flag is 0 for handles 0-5 (the "standard" handles) and 1 for other (non-standard) handles. Note that the noinherit flag applies only to this particular file descriptor; another descriptor obtained from _✓f_✓h by the _✓F_✓d_✓u_✓p system call or by use of the F_DUPFD option to _✓F_✓c_✓n_✓t_✓l will have the noinherit flag set to the default. Also note that these defaults are not the same as for the Unix operating system. F_GETFL Returns the user-settable file descriptor flags. These flags are the same as the mode passed to _✓F_✓o_✓p_✓e_✓n, unless they have been further modified by another _✓F_✓c_✓n_✓t_✓l operation. _✓a_✓r_✓g is ignored. F_SETFL Set user-settable file descriptor flags from the argument _✓a_✓r_✓g. Only the user-settable bits in _✓a_✓r_✓g are considered; the settings of other bits are ignored, but should be 0 for future compatibility. Version 0.95 MiNT Programmer's Manual 1 Fcntl(2) July 20, 1992 Fcntl(2) Moreover, it is not possible to change a file's read-write mode or sharing modes with this call; attempts to do so will (silently) fail. F_GETLK _✓a_✓r_✓g is a pointer to an flock structure: struct flock { short l_type; /* type of lock */ #define F_RDLCK 0 #define F_WRLCK 1 #define F_UNLCK 3 short l_whence; /* 0:file start, 1:current, 2:EOF */ long l_start; /* offset of locked region */ long l_len; /* 0 for rest of file */ short l_pid; /* set by F_GETLK */ }; If a lock exists which would prevent this lock from being applied to the file, the existing lock is copied into the structure and the l_pid field is set to the process id of the locking process. Oth- erwise, l_type is set to F_UNLCK. If a conflicting lock is held by a process on a different machine on a network, then the l_pid field will be set to a value defined by the network file system. This value will be in the range 0x1000 to 0xFFFF, and will therefore not conflict with any process id since process id's must be less than 0x1000. F_SETLK Set (if l_type is F_RDLCK or F_WRLCK) or clear (if l_type is F_UNLCK) an advisory lock on a file. If the file is a FIFO, the whole file must be locked or unlocked at once, i.e. l_whence, l_start, and l_len must be 0. If this lock would conflict with a lock held by another process, ELOCKED is returned. If an attempt is made to clear a non-existent lock, ENSLOCK is returned. More than one read lock may be placed on the same region of a file, but no write lock may overlap with any other sort of lock. If a process holds locks on a file, then the locks are automatically released whenever the process closes an open file handle referring to that file, or when the process terminates. FSTAT _✓a_✓r_✓g points to an XATTR structure, which is filled in with the appropriate extended file attributes for the file to which _✓f_✓d refers just as though the _✓F_✓x_✓a_✓t_✓t_✓r system call (q.v.) had been made on the file. FIONREAD _✓a_✓r_✓g points to a 32 bit integer, into which is writ- ten the number of bytes that are currently avail- able to be read from this descriptor; a read of Version 0.95 MiNT Programmer's Manual 2 Fcntl(2) July 20, 1992 Fcntl(2) this number of bytes or less should not cause the process to block (wait for more input). Note that for some files only an estimate can be provided, so the number is not always completely accurate. FIONWRITE _✓a_✓r_✓g points to a 32 bit integer, into which is writ- ten the number of bytes that may be written to the indicated file descriptor without causing the pro- cess to block. Note that for some files only an estimate can be provided, so the number is not always completely accurate. The following commands are valid for any terminal device, e.g. the console or a pseudo-terminal: TIOCGETP Get terminal parameters. _✓a_✓r_✓g is a pointer to a block of memory with the following structure: struct sgttyb { char sg_ispeed; /* reserved */ char sg_ospeed; /* reserved */ char sg_erase; /* erase character */ char sg_kill; /* line kill character */ short sg_flags; /* terminal control flags */ }; TIOCSETP Set terminal parameters from the struct sgttyb pointed to by _✓a_✓r_✓g. TIOCGETC Get terminal control characters. _✓a_✓r_✓g is a pointer to the following structure: struct tchars { char t_intrc; /* raises SIGINT */ char t_quitc; /* raises SIGQUIT */ char t_startc; /* starts terminal output */ char t_stopc; /* stops terminal output */ char t_eofc; /* marks end of file */ char t_brkc; /* marks end of line */ }; TIOCSETC Set terminal control characters from the struct tchars pointed to by _✓a_✓r_✓g. Setting any character to the value 0 causes the corresponding function to become unavailable. TIOCGLTC Get extended terminal control characters, and put them in the structure pointed to by _✓a_✓r_✓g: struct ltchars { char t_suspc; /* raises SIGTSTP now */ Version 0.95 MiNT Programmer's Manual 3 Fcntl(2) July 20, 1992 Fcntl(2) char t_dsuspc; /* raises SIGTSTP when read */ char t_rprntc; /* redraws the input line */ char t_flushc; /* flushes output */ char t_werasc; /* erases a word */ char t_lnextc; /* quotes a character */ }; TIOCSLTC Set extended terminal control characters from the struct ltchars pointed to by _✓a_✓r_✓g. Setting any of the characters to 0 causes the corresponding func- tion to become unavailable. TIOCGWINSZ _✓a_✓r_✓g has type "struct winsize *". The current window size for this window is placed in the structure pointed to by _✓a_✓r_✓g, which has the following fields: struct winsize { short ws_row; /* # of rows of text in window*/ short ws_col; /* # of columns of text */ short ws_xpixel; /* width of window in pixels */ short ws_ypixel; /* height of window in pixels */ }; If any fields in the structure are 0, this means that the corresponding value is unknown. TIOCSWINSZ _✓a_✓r_✓g has type "struct winsize *". The current window size for the window is set from the structure pointed to by _✓a_✓r_✓g. Note that the kernel maintains the information but does n✓no✓ot✓t act upon it in any way; it is up to window managers to perform what- ever physical changes are necessary to alter the window size, and to raise the SIGWINCH signal if necessary. TIOCGPGRP _✓a_✓r_✓g has type "long *"; the process group for the terminal is placed into the long pointed to by it. TIOCSPGRP _✓a_✓r_✓g has type "long *"; the process group for the terminal is set from the long pointed to by it. Processes in any other process group will be sent job control signals if they attempt input or output to the terminal. TIOCSTART Restart output to the terminal (as though the user typed control-Q) if it was stopped by a control-S or TIOCSTOP command. _✓a_✓r_✓g is ignored. TIOCSTOP Stop output to the terminal (as though the user Version 0.95 MiNT Programmer's Manual 4 Fcntl(2) July 20, 1992 Fcntl(2) typed control-S). _✓a_✓r_✓g is ignored. TIOCGXKEY Get the definition of a function or cursor key. _✓a_✓r_✓g is a pointer to a structure with the following fields: struct xkey { short xk_num; /* function key number */ char xk_def[8]; /* associated string */ }; The _✓x_✓k_✓__✓n_✓u_✓m field must be initialized with the num- ber of the desired key: xk_num Key 0-9 F1-F10 10-19 F11-F20 (shift F1-shift F10) 20 cursor up 21 cursor down 22 cursor right 23 cursor left 24 help 25 undo 26 insert 27 clr/home 28 shift+cursor up 29 shift+cursor down 30 shift+cursor right 31 shift+cursor left The string currently associated with the indicated key is copied into xk_def; this string is always null-terminated. TIOCSXKEY _✓a_✓r_✓g is a structure of type struct xkey, as defined above. Both the _✓x_✓k_✓__✓n_✓u_✓m and the _✓x_✓k_✓__✓d_✓e_✓f fields must be defined. After execution of this command, and if the XKEY bit is set in the _✓s_✓g_✓__✓f_✓l_✓a_✓g_✓s field of the sgttyb structure associated with the terminal, then if the indicated key is pressed on the affected terminal, any MiNT domain process using _✓F_✓r_✓e_✓a_✓d to read the key will get the string in _✓x_✓k_✓__✓d_✓e_✓f instead of ASCII 0. Note that this translation occurs only for MiNT domain processes and only for the _✓F_✓r_✓e_✓a_✓d system call. Also note that the string in _✓x_✓k_✓__✓d_✓e_✓f must be null terminated, and so at most 7 charac- ters may be assigned to any key. The following commands are valid only for processes opened as files: PBASEADDR _✓a_✓r_✓g is a pointer to a 32 bit integer, into which the address of the process basepage for the process to which _✓f_✓h refers is written. Version 0.95 MiNT Programmer's Manual 5 Fcntl(2) July 20, 1992 Fcntl(2) PPROCADDR _✓a_✓r_✓g is a pointer to a 32 bit integer, into which the address of the process control structure for the process is written. Note that this control structure differs from the one found in previous versions (before 0.93) of MiNT; it no longer includes the process context, so that this part of the structure may be changed without causing com- patibility problems. See the _✓P_✓C_✓T_✓X_✓T_✓S_✓I_✓Z_✓E command. PCTXTSIZE _✓a_✓r_✓g is a pointer to a 32 bit integer, into which the length of a process context structure is writ- ten. There are two of these structures located in memory just before the process control structure whose address is returned by the _✓P_✓P_✓R_✓O_✓C_✓A_✓D_✓D_✓R command. The first is the current process context; the sec- ond is the saved context from the last system call. The following commands are valid only for files which rep- resent shared memory. SHMSETBLK _✓a_✓r_✓g is a pointer to a block of memory previously allocated by _✓M_✓x_✓a_✓l_✓l_✓o_✓c. The memory will be offered for sharing under the name of the file represented by _✓f_✓d (which must be a file in the U:\SHM subdirec- tory). SHMGETBLK _✓a_✓r_✓g must be 0, for future compatibility. Returns the address of the block of memory previously asso- ciated with the file via _✓S_✓H_✓M_✓S_✓E_✓T_✓B_✓L_✓K, or a NULL pointer if an error occurs. Note that different processes may see the shared memory block at dif- ferent addresses in their address spaces. There- fore, the shared memory block should not contain any absolute pointers to data. R✓RE✓ET✓TU✓UR✓RN✓NS✓S 0 or a positive number if successful (for most commands; but see the specific descriptions above). EIHNDL if _✓f_✓h is not a valid GEMDOS open handle. EINVFN if the specified command is not valid for this file handle Some other (LONG) negative error number if an error occurs; different commands may recognize different possi- ble errors. Version 0.95 MiNT Programmer's Manual 6 Fcntl(2) July 20, 1992 Fcntl(2) S✓SE✓EE✓E A✓AL✓LS✓SO✓O _✓F_✓d_✓u_✓p(2), _✓F_✓l_✓o_✓c_✓k(2), _✓F_✓o_✓p_✓e_✓n(2), _✓F_✓x_✓a_✓t_✓t_✓r(2), _✓P_✓g_✓e_✓t_✓p_✓g_✓r_✓p(2), _✓P_✓s_✓e_✓t_✓p_✓g_✓r_✓p(2) B✓BU✓UG✓GS✓S Very little error checking is done. In particular, owner- ship of terminals is not properly checked, nor is read/write access to the files. Do not rely on this bug; it will be fixed some day. File locking is not yet implemented for most file systems. Very few of the terminal control options have effect on terminals connected via serial ports or midi. In particu- lar, it is not possible to set the baud rate, parity, flow control, or similar options with _✓F_✓c_✓n_✓t_✓l. However, this bug will be fixed in future versions of the operating system, so programs should never modify the sg_ispeed, sg_ospeed, or sg_flags fields of the sgttyb structure, and should always use TIOCGETP to obtain the original settings of these fields before calling TIOCSETP. Version 0.95 MiNT Programmer's Manual 7